home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / zgegs.z / zgegs
Encoding:
Text File  |  2002-10-03  |  8.2 KB  |  199 lines
  1.  
  2.  
  3.  
  4. ZZZZGGGGEEEEGGGGSSSS((((3333SSSS))))                                                            ZZZZGGGGEEEEGGGGSSSS((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ZGEGS - routine is deprecated and has been replaced by routine ZGGES
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      SUBROUTINE ZGEGS( JOBVSL, JOBVSR, N, A, LDA, B, LDB, ALPHA, BETA, VSL,
  13.                        LDVSL, VSR, LDVSR, WORK, LWORK, RWORK, INFO )
  14.  
  15.          CHARACTER     JOBVSL, JOBVSR
  16.  
  17.          INTEGER       INFO, LDA, LDB, LDVSL, LDVSR, LWORK, N
  18.  
  19.          DOUBLE        PRECISION RWORK( * )
  20.  
  21.          COMPLEX*16    A( LDA, * ), ALPHA( * ), B( LDB, * ), BETA( * ), VSL(
  22.                        LDVSL, * ), VSR( LDVSR, * ), WORK( * )
  23.  
  24. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  25.      These routines are part of the SCSL Scientific Library and can be loaded
  26.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  27.      directs the linker to use the multi-processor version of the library.
  28.  
  29.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  30.      4 bytes (32 bits). Another version of SCSL is available in which integers
  31.      are 8 bytes (64 bits).  This version allows the user access to larger
  32.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  33.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  34.      only one of the two versions; 4-byte integer and 8-byte integer library
  35.      calls cannot be mixed.
  36.  
  37. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  38.      This routine is deprecated and has been replaced by routine ZGGES. ZGEGS
  39.      computes for a pair of N-by-N complex nonsymmetric matrices A, B:  the
  40.      generalized eigenvalues (alpha, beta), the complex Schur form (A, B), and
  41.      optionally left and/or right Schur vectors (VSL and VSR).
  42.  
  43.      (If only the generalized eigenvalues are needed, use the driver ZGEGV
  44.      instead.)
  45.  
  46.      A generalized eigenvalue for a pair of matrices (A,B) is, roughly
  47.      speaking, a scalar w or a ratio  alpha/beta = w, such that  A - w*B is
  48.      singular.  It is usually represented as the pair (alpha,beta), as there
  49.      is a reasonable interpretation for beta=0, and even for both being zero.
  50.      A good beginning reference is the book, "Matrix Computations", by G.
  51.      Golub & C. van Loan (Johns Hopkins U. Press)
  52.  
  53.      The (generalized) Schur form of a pair of matrices is the result of
  54.      multiplying both matrices on the left by one unitary matrix and both on
  55.      the right by another unitary matrix, these two unitary matrices being
  56.      chosen so as to bring the pair of matrices into upper triangular form
  57.      with the diagonal elements of B being non-negative real numbers (this is
  58.      also called complex Schur form.)
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ZZZZGGGGEEEEGGGGSSSS((((3333SSSS))))                                                            ZZZZGGGGEEEEGGGGSSSS((((3333SSSS))))
  71.  
  72.  
  73.  
  74.      The left and right Schur vectors are the columns of VSL and VSR,
  75.      respectively, where VSL and VSR are the unitary matrices
  76.      which reduce A and B to Schur form:
  77.  
  78.      Schur form of (A,B) = ( (VSL)**H A (VSR), (VSL)**H B (VSR) )
  79.  
  80.  
  81. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  82.      JOBVSL   (input) CHARACTER*1
  83.               = 'N':  do not compute the left Schur vectors;
  84.               = 'V':  compute the left Schur vectors.
  85.  
  86.      JOBVSR   (input) CHARACTER*1
  87.               = 'N':  do not compute the right Schur vectors;
  88.               = 'V':  compute the right Schur vectors.
  89.  
  90.      N       (input) INTEGER
  91.              The order of the matrices A, B, VSL, and VSR.  N >= 0.
  92.  
  93.      A       (input/output) COMPLEX*16 array, dimension (LDA, N)
  94.              On entry, the first of the pair of matrices whose generalized
  95.              eigenvalues and (optionally) Schur vectors are to be computed.
  96.              On exit, the generalized Schur form of A.
  97.  
  98.      LDA     (input) INTEGER
  99.              The leading dimension of A.  LDA >= max(1,N).
  100.  
  101.      B       (input/output) COMPLEX*16 array, dimension (LDB, N)
  102.              On entry, the second of the pair of matrices whose generalized
  103.              eigenvalues and (optionally) Schur vectors are to be computed.
  104.              On exit, the generalized Schur form of B.
  105.  
  106.      LDB     (input) INTEGER
  107.              The leading dimension of B.  LDB >= max(1,N).
  108.  
  109.      ALPHA   (output) COMPLEX*16 array, dimension (N)
  110.              BETA    (output) COMPLEX*16 array, dimension (N) On exit,
  111.              ALPHA(j)/BETA(j), j=1,...,N, will be the generalized eigenvalues.
  112.              ALPHA(j), j=1,...,N  and  BETA(j), j=1,...,N  are the diagonals
  113.              of the complex Schur form (A,B) output by ZGEGS.  The  BETA(j)
  114.              will be non-negative real.
  115.  
  116.              Note: the quotients ALPHA(j)/BETA(j) may easily over- or
  117.              underflow, and BETA(j) may even be zero.  Thus, the user should
  118.              avoid naively computing the ratio alpha/beta.  However, ALPHA
  119.              will be always less than and usually comparable with norm(A) in
  120.              magnitude, and BETA always less than and usually comparable with
  121.              norm(B).
  122.  
  123.      VSL     (output) COMPLEX*16 array, dimension (LDVSL,N)
  124.              If JOBVSL = 'V', VSL will contain the left Schur vectors.  (See
  125.              "Purpose", above.)  Not referenced if JOBVSL = 'N'.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ZZZZGGGGEEEEGGGGSSSS((((3333SSSS))))                                                            ZZZZGGGGEEEEGGGGSSSS((((3333SSSS))))
  137.  
  138.  
  139.  
  140.      LDVSL   (input) INTEGER
  141.              The leading dimension of the matrix VSL. LDVSL >= 1, and if
  142.              JOBVSL = 'V', LDVSL >= N.
  143.  
  144.      VSR     (output) COMPLEX*16 array, dimension (LDVSR,N)
  145.              If JOBVSR = 'V', VSR will contain the right Schur vectors.  (See
  146.              "Purpose", above.)  Not referenced if JOBVSR = 'N'.
  147.  
  148.      LDVSR   (input) INTEGER
  149.              The leading dimension of the matrix VSR. LDVSR >= 1, and if
  150.              JOBVSR = 'V', LDVSR >= N.
  151.  
  152.      WORK    (workspace/output) COMPLEX*16 array, dimension (LWORK)
  153.              On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  154.  
  155.      LWORK   (input) INTEGER
  156.              The dimension of the array WORK.  LWORK >= max(1,2*N).  For good
  157.              performance, LWORK must generally be larger.  To compute the
  158.              optimal value of LWORK, call ILAENV to get blocksizes (for
  159.              ZGEQRF, ZUNMQR, and CUNGQR.)  Then compute:  NB  -- MAX of the
  160.              blocksizes for ZGEQRF, ZUNMQR, and CUNGQR; the optimal LWORK is
  161.              N*(NB+1).
  162.  
  163.              If LWORK = -1, then a workspace query is assumed; the routine
  164.              only calculates the optimal size of the WORK array, returns this
  165.              value as the first entry of the WORK array, and no error message
  166.              related to LWORK is issued by XERBLA.
  167.  
  168.      RWORK   (workspace) DOUBLE PRECISION array, dimension (3*N)
  169.  
  170.      INFO    (output) INTEGER
  171.              = 0:  successful exit
  172.              < 0:  if INFO = -i, the i-th argument had an illegal value.
  173.              =1,...,N:  The QZ iteration failed.  (A,B) are not in Schur form,
  174.              but ALPHA(j) and BETA(j) should be correct for j=INFO+1,...,N.  >
  175.              N:  errors that usually indicate LAPACK problems:
  176.              =N+1: error return from ZGGBAL
  177.              =N+2: error return from ZGEQRF
  178.              =N+3: error return from ZUNMQR
  179.              =N+4: error return from ZUNGQR
  180.              =N+5: error return from ZGGHRD
  181.              =N+6: error return from ZHGEQZ (other than failed iteration)
  182.              =N+7: error return from ZGGBAK (computing VSL)
  183.              =N+8: error return from ZGGBAK (computing VSR)
  184.              =N+9: error return from ZLASCL (various places)
  185.  
  186. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  187.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  188.  
  189.      This man page is available only online.
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.